<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>User Guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css" />
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="alias.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="alias.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>



<script type="text/javascript">
  jQuery(document).ready(function () {
    if(gref){ // Number all _img and _table classes
      gref();
    }
  });
</script>

</head>
<body>
<div id="top"><!-- do not remove this div! -->

<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">nRF Enhanced Shockburst
   &#160;<span id="projectnumber">version 0.4.2</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('group__esb__users__guide.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">User Guide</div>  </div>
<div class="ingroups"><a class="el" href="group__modules__02__esb.html">Enhanced ShockBurst</a></div></div>
<div class="contents">
<h2><a class="anchor" id="esb_intro"></a>
Introduction</h2>
<p>Enhanced ShockBurst (ESB) is a basic protocol supporting two-way data packet communication including packet buffering, packet acknowledgement and automatic retransmission of lost packets.</p>
<p>The ESB protocol was embedded in hardware in the legacy nRF24Lxx series from Nordic Semiconductor. The nRF51 ESB software library enables an nRF51 device to communicate with a nRF24Lxx device using the ESB protocol.</p>
<p>ESB features automatic packet transaction handling for easy implementation of a reliable bi-directional data link. A transaction is a packet exchange between two transceivers, with one transceiver acting as the Primary Receiver (PRX) and the other transceiver acting as the Primary Transmitter (PTX).</p>
<div class="image">
<img src="esb_fig1_star_network.png" alt="esb_fig1_star_network.png"/>
<div class="caption">
Enhanced ShockBurst network</div></div>
 <h2><a class="anchor" id="features"></a>
Features</h2>
<ul>
<li>Supports a star network topology with typically one Primary Receiver (PRX) and up to 8 Primary Transmitters (PTX).</li>
<li>1 to 32 bytes dynamic payload length.</li>
<li>Bi-directional data transfer between each PTX and the PRX.</li>
<li>Packet acknowledgement and automatic packet retransmission functionality eliminates loss of data.</li>
<li>Individual TX and RX FIFOs for every pipe.</li>
<li>Backward compatible with legacy nRF24Lxx Enhanced ShockBurst.</li>
</ul>
<h2><a class="anchor" id="esb_transaction"></a>
Packet transaction</h2>
<p>An Enhanced ShockBurst packet transaction is initiated by a packet transmission from the PTX and successfully completed when the PTX has received an acknowledgment packet (ACK packet) in return from the PRX.</p>
<p>To enable a bi-directional data link the PRX is allowed to attach a data payload to the ACK packet. This can be done by uploading packet(s) to the TX FIFO(s) on the PRX.</p>
<div class="image">
<img src="esb_fig2_ptx_trans_ok.png" alt="esb_fig2_ptx_trans_ok.png"/>
<div class="caption">
PTX to PRX packet transaction</div></div>
<p> If the PTX does not receive the ACK after the initial transmitted packet, it will attempt to retransmit the packet until the ACK is finally being received. The maximum number of allowed retransmission attempts are specified by the <a class="el" href="group__esb__02__api.html#ga8cdcef8f56272380546af260bcea0ad8" title="Set the maximum number of TX attempts that can be used for a single packet.">nrf_esb_set_max_number_of_tx_attempts()</a> function, and the delay in between each transmission attempt is specified using the <a class="el" href="group__esb__02__api.html#gaf745d55ede0ad93b7e24af33e3ef9df2" title="Set the retransmission delay.">nrf_esb_set_retransmit_delay()</a> function.</p>
<p>The retransmission delay is defined as the duration between the start of each transmission attempt. Note that this differs from the legacy nRF24Lxx hardware implementation, where this delay was defined as the duration from the end of a packet transmission until the start of the retransmission.</p>
<p>In the case where only the ACK packet sent from the PRX to the PTX is lost, but both the initial packet and the subsequent retransmission attempts are being successfully received by the PRX, the repeated packets will be discarded by the PRX, but the ACK packets will still be sent in return to the PTX. This prevents the application receiving duplicate data packets at the PRX.</p>
<div class="image">
<img src="esb_fig3_prx_ptx_trans_fail.png" alt="esb_fig3_prx_ptx_trans_fail.png"/>
<div class="caption">
Failed package transaction</div></div>
<p>.</p>
<p>A PTX can select that individual packets transmitted to the PRX shall not require an ACK to be sent in return from the PRX. This decision is taken by the application when uploading a packet to the TX FIFO using the <b>packet_type</b> parameter of the <a class="el" href="group__esb__02__api.html#ga23388e992626680973998c4485ab680a" title="Add a packet to the tail of the TX FIFO.">nrf_esb_add_packet_to_tx_fifo()</a> function.</p>
<p>When the PRX receives a packet not requiring an ACK it will not send an ACK packet in return to the PTX, and as a result the PTX will continue retransmitting the packet until the maximum number of allowed retransmission attempts is reached.</p>
<h2><a class="anchor" id="getting_started"></a>
Getting started</h2>
<p>The typical ESB application has the following steps:</p>
<ul>
<li>Initialize ESB using <a class="el" href="group__esb__02__api.html#ga155377fe2e8a0b40352c21a5ec7979ec" title="Initialize ESB.">nrf_esb_init()</a>.</li>
<li>Reconfigure the ESB default parameters if needed.</li>
<li>Enable ESB using <a class="el" href="group__esb__02__api.html#gaa7f7be8b058378a3b31d38ce88e0600f" title="Enable ESB.">nrf_esb_enable()</a>.</li>
<li>If the node is a PTX, start sending:<ul>
<li>Add payloads to the transmit (TX) FIFO using <a class="el" href="group__esb__02__api.html#ga23388e992626680973998c4485ab680a" title="Add a packet to the tail of the TX FIFO.">nrf_esb_add_packet_to_tx_fifo()</a>.</li>
<li>Handle the resulting callback that is <a class="el" href="group__esb__02__api.html#ga416a6ef0fc94e7df9054e71c8784095a" title="TX success callback.">nrf_esb_tx_success()</a> if an ACK was successfully received, an additional <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> if the ACK contained a payload or <a class="el" href="group__esb__02__api.html#ga03993c4e0419bbcac77aa0965ecce6ad" title="TX failed callback (PTX mode only).">nrf_esb_tx_failed()</a> if no ACK packet was received on any of the retransmission attempts. Failed packets (not receiving an ACK) are automatically removed from the TX FIFO.</li>
</ul>
</li>
<li>If the node is a PRX, start listening:<ul>
<li>Handle the received data packets when the <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> callback is called. The received packets are fetched from the RX FIFO using the <a class="el" href="group__esb__02__api.html#gaef1dcdb47f1c29b01badecdeb6fb3459" title="Fetch a packet from the head of the RX FIFO.">nrf_esb_fetch_packet_from_rx_fifo()</a> function.</li>
<li>Payloads to can be attached to ACK packets by adding these to the TX FIFO using <a class="el" href="group__esb__02__api.html#ga23388e992626680973998c4485ab680a" title="Add a packet to the tail of the TX FIFO.">nrf_esb_add_packet_to_tx_fifo()</a>. If an ACK payload is assumed successfully received by the PTX, that is when a new packet sent from the PTX is received by the PRX, the <a class="el" href="group__esb__02__api.html#ga416a6ef0fc94e7df9054e71c8784095a" title="TX success callback.">nrf_esb_tx_success()</a> callback will be called and the sent packet is automatically removed from the TX FIFO.</li>
</ul>
</li>
</ul>
<p>ESB can also be disabled at any time using the <a class="el" href="group__esb__02__api.html#ga1888b9ea163638d761af804e89de4122" title="Disable ESB.">nrf_esb_disable()</a> function. When this is called ESB will complete any ongoing transaction before being disabled. When any ongoing transaction is completed and ESB has been disabled, the <a class="el" href="group__esb__02__api.html#ga5e82709bd23aa952a883db3af5b987e0" title="Disabled callback.">nrf_esb_disabled()</a> callback will be called.</p>
<h2><a class="anchor" id="freq_select"></a>
Frequency selection</h2>
<p>ESB can send or receive packets using one of 126 frequency channels as selected by the function <a class="el" href="group__esb__02__api.html#gaca97648d85e0dcb1dde56545efb36df8" title="Set the Radio Frequency (RF) channel.">nrf_esb_set_channel()</a>.</p>
<p>In order to exchange packets between a PTX and a PRX these must be configured using the same frequency channel.</p>
<h2><a class="anchor" id="addressing"></a>
Pipes and addressing</h2>
<p>Each PTX or PRX node uses the term "pipe" as a logical address for communication with another node. Each pipe maps to one actual physical on-air address used when transmitting or receiving packets.</p>
<p>The actual on-air physical addresses are composed of a 2-4 byte long "base address" in addition to a 1 byte prefix address. Note that the nRF51 radio uses an alternating sequence of 0s and 1s as the preamble of the packet. Therefore for packets to be received correctly, the most significant byte of the base address should not be an alternating sequence of 0s and 1s i.e. it should not be 0x55 or 0xAA.</p>
<p>Pipe 0 has its own unique base address, which is base address 0, while pipes 1-7 use the same base address, which is base address 1.</p>
<p>Each of the 8 pipes have a unique byte-long prefix address.</p>
<p>On air, the most significant bit of each address byte will be transmitted first. The most significant byte of the 4 byte long base address is the first transmitted address byte, while the prefix byte is transmitted last.</p>
<h2><a class="anchor" id="packet_id"></a>
Packet identification</h2>
<p>Any packet transmitted from a PTX to a PRX is uniquely identified by a two bit packet ID field (PID) in the packet header together with the packet's Cyclic Redundancy Check (CRC) field. This packet ID is used to distinguish a new packet from the previous packet if it has the same payload.</p>
<p>At the PRX, retransmitted packets will be discarded and not added to an RX FIFO. The <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> will not be called.</p>
<p>The CRC is used in addition to the PID to identify a unique packet. This reduces the likelihood of a packet being falsely identified as a retransmission attempt and discarded by the PRX when several consecutive failed packet transmission attempts occur. This feature is helpful as the PID is only two bits.</p>
<h2><a class="anchor" id="FIFOs"></a>
FIFOs</h2>
<p>All eight pipes on both the PTX and the PRX have two multi level FIFOs that can hold packets, that is each pipe's TX FIFO and RX FIFO.</p>
<h3><a class="anchor" id="ptx_fifo"></a>
PTX FIFO handling</h3>
<p>When ESB is enabled in PTX mode, any packets uploaded to a TX FIFO will be transmitted at the next opportunity. If several TX FIFOs contain packets, the various TX FIFOs will be serviced in a round robin fashion, meaning that no TX FIFO will experience starvation even when packets are continuously being added to other TX FIFOs.</p>
<p>When an ACK is successfully received from a PRX, it implies that the payload was successfully received and added to the PRX's RX FIFO, the successfully transmitted packet will be removed from the TX FIFO so that the next packet in the FIFO can be transmitted.</p>
<p>If an ACK received by a PTX contains a payload, this payload will be added to the pipe's RX FIFO.</p>
<p>If the RX FIFO for a specific pipe on a PTX is full and can not accommodate any new packets, no new packets will be sent from the PTX on this pipe. In this case, we will never end up in the situation where a payload received in an ACK will have to be discarded due to the pipe's RX FIFO being full.</p>
<p>In addition, ESB limits the total number of packets in the FIFOs, which is smaller than the total size of all the FIFOs. Therefore, a PTX will also refuse to add a packet to the TX FIFO if it doesn't have space for the packet as well as the corresponding ACK.</p>
<h3><a class="anchor" id="prx_FIFO"></a>
PRX FIFO handling</h3>
<p>When ESB is enabled in PRX mode, all enabled pipes (addresses) are simultaneously monitored for incoming packets.</p>
<p>If a new packet not previously added to the pipe's RX FIFO is received, and the pipe's RX FIFO has available space for the packet, the packet will be added to the RX FIFO and an ACK will be sent in return to the PTX. If the pipe's TX FIFO contains any packets, the next serviceable packet in the TX FIFO will be attached as a payload in the ACK packet. In order for a TX packet to be attached to an ACK, this TX packet would have to be uploaded to the TX FIFO before the packet is received.</p>
<p>As we can not ensure that the ACK always will be successfully received by the PTX, the data payload added to the ACK will not be removed from the TX FIFO immediately. This TX packet will be removed from the TX FIFO when a new packet (new packet ID or CRC) is received on the same pipe. In this case, the new packet sent as an ACK will serve as a kind of acknowledgement from the PTX saying that the previous ACK from the PRX was successfully received by the PTX. ACKs sent in reply to retransmission attempts will all contain the same TX payload.</p>
<h2><a class="anchor" id="callback_queuing"></a>
Callback queuing</h2>
<p>ESB contains an internal callback queue for queuing pending callbacks. This allows the application to queue callback functions while the application is already servicing a previously called callback function. In addition this allows the ESB process to function uninterrupted.</p>
<p>As an example, if a new packet is being received while the application is already servicing the <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> callback from a previously received packet, the <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> callback for the latest packet will be added to the callback queue and serviced at a later opportunity. In this case, <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> will be called one time for every received packet, and the application does not need to handle the potential race condition scenario where a new packet is being received just before the application is about to exit the <a class="el" href="group__esb__02__api.html#gab3042dde4c3151c1517f4998378f52ce" title="RX data ready callback.">nrf_esb_rx_data_ready()</a> function.</p>
<p>Similarly, ESB will call the <a class="el" href="group__esb__02__api.html#ga416a6ef0fc94e7df9054e71c8784095a" title="TX success callback.">nrf_esb_tx_success()</a> once for every transmitted packet, even when a new packet is being transmitted while the application is servicing the <a class="el" href="group__esb__02__api.html#ga416a6ef0fc94e7df9054e71c8784095a" title="TX success callback.">nrf_esb_tx_success()</a> callback of a previously transmitted packet.</p>
<p>The callback queue can hold up to 10 pending callback functions.</p>
<h2><a class="anchor" id="gzll_config"></a>
Resources</h2>
<p>ESB makes use of the following resources and requires exclusive access to them in order for ESB to ensure correct operation:</p>
<ul>
<li>Radio (NRF_RADIO)</li>
<li>Timer (NRF_TIMER2)</li>
<li>PPI Channels 0, 1 and 2</li>
<li>Software interrupt 10 for the ESB callback functions</li>
</ul>
<p>The radio and timer interrupt handlers run at priority level 0 (highest level), and the ESB callback functions run at priority level 1. Applications should run at priority level 2 or higher in order to ensure correct operation. </p>
</div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">
      Copyright &copy 2006-2011 <a href="http://www.nordicsemi.no" style="text-decoration:none">Nordic Semiconductor</a>.
      All Rights Reserved.
      <a href="disclaimer.html">Disclaimer</a>
    </li>
   </ul>
 </div>


</body>
</html>
